---
title: SAIF.Business.Policy architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for the shared base policy library.
status: draft
owner: SAIF Claims BOF team
last_reviewed: 2026-08-21
library: SAIF.Business.Policy
reference_type: embedded
---

# SAIF.Business.Policy architecture

`SAIF.Business.Policy` is a mid-tier VB.NET class library with no program entry points, functioning as a shared "base" policy library.* It provides a small set of read-only BOF business objects, cached code-table lookups, cross-cutting interfaces/enums/constants, and a static ad hoc data-access helper class, and it has zero local project dependencies within this repository.

## Responsibilities
- Provide retrieve-only BOF business objects — `clsHazardGroup` and `clsHazardGroupCollection` — for hazard-group code/rate classification lookups.
- Provide cached, lazily-loaded code-table lookup wrappers (`clsBenefitJurisdictionCodeMap`, `clsManualClassTypeCodeMap`) built on the framework's `clsCodeTableBase.ExtendedCodeMap`†.
- Define cross-cutting contracts, enums, and constants consumed by richer downstream policy libraries and by the presentation/view business tier: `IPolicyHeaderDataProvider`, `IPolicyAssociationType`, `IPolicyAssociation`, `IPolicyHeaderAssociation`, `iPeriodRatingInfo`, `iPolicyPeriodBase`, `Enums`, `Constants`.
- Supply ad hoc, static scalar/stored-procedure data-access helpers via `PolicyInformation` (e.g., maximum policy effective date, policy-period expiration date, anniversary rate date, market type) that bypass the standard BOF business-object pattern.

## Component boundaries
- **BOF business objects** (`clsHazardGroup`, `clsHazardGroupCollection`): retrieve-only objects following the standard framework `Criteria`/`IBusinessCriteria` pattern; all mutating SQL properties throw `ApplicationException`.
- **Code-table maps** (`CodeMaps\clsBenefitJurisdictionCodeMap`, `CodeMaps\clsManualClassTypeCodeMap`): cached lookup wrappers exposed only through `Friend`-constructor factory methods on the `CodeMaps` static class.
- **Cross-layer contracts** (`IPolicyHeaderDataProvider`, `IPolicyAssociationType`, `IPolicyAssociation`, `IPolicyHeaderAssociation`, `iPeriodRatingInfo`, `iPolicyPeriodBase`, `PeriodRatingInfoExtensions`): interfaces/enums implemented downstream, notably by `SAIF.Business.View.Policy` (`clsAssociationType`, `clsAssociationTypeCode`, `clsPolicyAssociation`).
- **Ad hoc data-access helper** (`PolicyInformation` and its private `SQL` nested class): static/shared properties issuing inline SQL and one stored-procedure call directly against `IDataPortalInfo`/`IDataAccess`, without a `Criteria` wrapper — an application-layer-style shortcut embedded in the business tier.
- **Value/enum support** (`clsTranslationResult`, `Enums`, `Constants`, `StandardAssociationTypes`, `PolicyAssociationTypeCategories`, `AdjustedRates`, `iAdjustedRateFactor`, `iAdjustedRateProvider`): shared value objects, domain enums, and constants used across the policy domain.
- **Orphaned artifact** (`Institutions` typed `DataSet`): generated bank/institution reference-data DataSet with no confirmed consumer within this library's own source.**

## Interaction model
- `clsHazardGroupCollection` follows the standard BOF collection retrieve pattern: `BeforeRetrieve` builds an `IDataRequest` from `Criteria.RetrieveSQL`, the framework's data portal executes it, and `AfterRetrieve` iterates the `IDataReader` result to construct child `clsHazardGroup` instances via `Load()` → `Fill()` → `MarkOld()`†.
- `PolicyInformation` interacts with `IDataPortalInfo`/`IDataAccess`/`IPortalRequest`/`IDataRequest` directly as static/shared properties, without a `Criteria`/`IBusinessCriteria` wrapper, for simple scalar or stored-procedure lookups.
- The interfaces defined in this library (`IPolicyHeaderDataProvider`, `IPolicyAssociationType`, `IPolicyAssociation`, `IPolicyHeaderAssociation`) are implemented downstream in `SAIF.Business.View.Policy`, establishing this library's role as a shared-contract provider consumed by the presentation/view business tier rather than an implementer of policy behavior itself.
- No outbound project references exist from this library (`SAIF.Business.Policy.vbproj` has zero `<ProjectReference>` elements); all references are binary/NuGet references, placing this library at the base of the dependency graph for the policy domain.*

## Design constraints
- All business objects in this library are explicitly retrieve-only; mutating SQL properties in `clsHazardGroup.Criteria` and `clsHazardGroupCollection.Criteria` throw `ApplicationException(clsConstants.Messages.InvalidSQLProperty)` and are never invoked.
- `clsBenefitJurisdictionCodeMap` and `clsManualClassTypeCodeMap` constructors are `Friend`-scoped; instances must be obtained through the `CodeMaps` static factory, enforcing single-instance caching semantics.
- `PolicyInformation`'s data-access shortcuts have no error handling for `Nothing`/`DBNull` cast results (e.g., `MaxPolicyEffectiveDate`), which would raise a cast exception if the underlying query returns no matching row.**
- The `Institutions` typed DataSet is generated but has no confirmed consumer in this library's source; its purpose and downstream usage could not be confirmed from the scanned files.**
- This library inherits its business-object lifecycle (edit session management, rule evaluation, save/retrieve dispatch) from `clsBusinessBase`† and `clsBusinessCollection`† in `SAIF.Framework.Core`, tying `clsHazardGroup`/`clsHazardGroupCollection` to the framework's V1 rules engine (`clsRulesManager`) and data-portal dispatch path†.

## Architecture diagram
The following diagram shows the high-level component boundaries within this library and its relationship to the framework base classes and downstream consumers.

```mermaid
flowchart TD
	FW["SAIF.Framework.Core<br>clsBusinessBase / clsBusinessCollection"] --> HG["clsHazardGroup /<br>clsHazardGroupCollection<br>(retrieve-only BOF objects)"]
	FW --> CM["CodeMaps<br>clsBenefitJurisdictionCodeMap /<br>clsManualClassTypeCodeMap"]
	HG --> DB[("Oracle database<br>HAZARD_GROUP")]
	CM --> DB2[("Oracle database<br>BENEFIT_JURISDICTION_CODE /<br>MANUAL_CLASS_TYPE_CODE")]
	PI["PolicyInformation<br>(static ad hoc data-access helper)"] --> DB3[("Oracle database<br>POLICY / POLICY_PERIOD / etc.")]
	Contracts["Cross-layer contracts<br>IPolicyHeaderDataProvider,<br>IPolicyAssociationType,<br>iPeriodRatingInfo, iPolicyPeriodBase"]
	Consumer["SAIF.Business.View.Policy<br>(clsAssociationType, clsPolicyAssociation)"] -->|implements| Contracts
	Consumer -->|Project Reference| ThisLib["SAIF.Business.Policy"]
	ThisLib --> HG
	ThisLib --> CM
	ThisLib --> PI
	ThisLib --> Contracts
```

## Sequence diagram
The following diagram shows the primary retrieve sequence for hazard groups effective on a given date.

```mermaid
sequenceDiagram
	participant Caller
	participant Collection as clsHazardGroupCollection
	participant Portal as Data portal (SAIF.Framework.Core)
	participant DB as Oracle database
	Caller->>Collection: GetHazardGroups(inDataportal, inEffectiveDate)
	Collection->>Collection: BeforeRetrieve (build Criteria.RetrieveSQL)
	Collection->>Portal: RetrieveObject(Criteria)
	Portal->>DB: Execute SELECT with EffectiveDate parameter
	DB-->>Portal: IDataReader result rows
	Portal-->>Collection: AfterRetrieve (IDataReader)
	Collection->>Collection: Create clsHazardGroup, Load/Fill/MarkOld per row
	Collection-->>Caller: clsHazardGroupCollection
```

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified. Statements marked with †
> were retrieved from a dependency library's own documentation via the Legends CLI RAG service.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [API reference](api/index.md)
- [SAIF.Business.View.Policy](../saif-business-view-policy/overview.md)

## Sources
- `.saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/analysis/TSK006-analysis.md`
- `.saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/analysis/TSK1B-004-dbanalysis-saif-business-policy.md`
- `.saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/dependency-resolution.json`